<!DOCTYPE html>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
<title>libtorrent</title>
<meta name="description" content="A feature complete BitTorrent protocol implementation as a C++ library">
<meta name=viewport content="width=device-width, initial-scale=1">
<meta property="og:image" content="img/logo-color.png" />
<meta property="og:site_name" content="libtorrent" />
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document">
    <div id="container">
    <a href="index.html">
    <img src="img/logo-color-text.png" alt="libtorrent logo"/>
    </a>
    <div>

<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Version:</th>
<td>2.0.11</td></tr>
</tbody>
</table>
<p><a class="reference external" href="reference.html">home</a></p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#a-word-of-caution" id="toc-entry-1">a word of caution</a></li>
<li><a class="reference internal" href="#plugin-interface" id="toc-entry-2">plugin-interface</a></li>
<li><a class="reference internal" href="#custom-alerts" id="toc-entry-3">custom alerts</a></li>
<li><a class="reference internal" href="#peer-connection-handle" id="toc-entry-4">peer_connection_handle</a></li>
<li><a class="reference internal" href="#bt-peer-connection-handle" id="toc-entry-5">bt_peer_connection_handle</a></li>
<li><a class="reference internal" href="#plugin" id="toc-entry-6">plugin</a><ul>
<li><a class="reference internal" href="#implemented-features" id="toc-entry-7">implemented_features()</a></li>
<li><a class="reference internal" href="#new-torrent" id="toc-entry-8">new_torrent()</a></li>
<li><a class="reference internal" href="#added" id="toc-entry-9">added()</a></li>
<li><a class="reference internal" href="#abort" id="toc-entry-10">abort()</a></li>
<li><a class="reference internal" href="#on-dht-request" id="toc-entry-11">on_dht_request()</a></li>
<li><a class="reference internal" href="#on-alert" id="toc-entry-12">on_alert()</a></li>
<li><a class="reference internal" href="#on-unknown-torrent" id="toc-entry-13">on_unknown_torrent()</a></li>
<li><a class="reference internal" href="#on-tick" id="toc-entry-14">on_tick()</a></li>
<li><a class="reference internal" href="#get-unchoke-priority" id="toc-entry-15">get_unchoke_priority()</a></li>
<li><a class="reference internal" href="#load-state" id="toc-entry-16">load_state()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#torrent-plugin" id="toc-entry-17">torrent_plugin</a><ul>
<li><a class="reference internal" href="#new-connection" id="toc-entry-18">new_connection()</a></li>
<li><a class="reference internal" href="#on-piece-pass-on-piece-failed" id="toc-entry-19">on_piece_pass() on_piece_failed()</a></li>
<li><a class="reference internal" href="#tick" id="toc-entry-20">tick()</a></li>
<li><a class="reference internal" href="#on-pause-on-resume" id="toc-entry-21">on_pause() on_resume()</a></li>
<li><a class="reference internal" href="#on-files-checked" id="toc-entry-22">on_files_checked()</a></li>
<li><a class="reference internal" href="#on-state" id="toc-entry-23">on_state()</a></li>
<li><a class="reference internal" href="#on-add-peer" id="toc-entry-24">on_add_peer()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#peer-plugin" id="toc-entry-25">peer_plugin</a><ul>
<li><a class="reference internal" href="#type" id="toc-entry-26">type()</a></li>
<li><a class="reference internal" href="#add-handshake" id="toc-entry-27">add_handshake()</a></li>
<li><a class="reference internal" href="#on-disconnect" id="toc-entry-28">on_disconnect()</a></li>
<li><a class="reference internal" href="#on-connected" id="toc-entry-29">on_connected()</a></li>
<li><a class="reference internal" href="#on-handshake" id="toc-entry-30">on_handshake()</a></li>
<li><a class="reference internal" href="#on-extension-handshake" id="toc-entry-31">on_extension_handshake()</a></li>
<li><a class="reference internal" href="#on-have-all-on-interested-on-choke-on-dont-have-on-bitfield-on-have-on-request-on-have-none-on-allowed-fast-on-unchoke-on-not-interested" id="toc-entry-32">on_have_all() on_interested() on_choke() on_dont_have() on_bitfield() on_have() on_request() on_have_none() on_allowed_fast() on_unchoke() on_not_interested()</a></li>
<li><a class="reference internal" href="#on-piece" id="toc-entry-33">on_piece()</a></li>
<li><a class="reference internal" href="#sent-unchoke-sent-not-interested-sent-have-sent-interested-sent-piece" id="toc-entry-34">sent_unchoke() sent_not_interested() sent_have() sent_interested() sent_piece()</a></li>
<li><a class="reference internal" href="#sent-payload" id="toc-entry-35">sent_payload()</a></li>
<li><a class="reference internal" href="#can-disconnect" id="toc-entry-36">can_disconnect()</a></li>
<li><a class="reference internal" href="#on-extended" id="toc-entry-37">on_extended()</a></li>
<li><a class="reference internal" href="#on-unknown-message" id="toc-entry-38">on_unknown_message()</a></li>
<li><a class="reference internal" href="#on-piece-pass-on-piece-failed-1" id="toc-entry-39">on_piece_pass() on_piece_failed()</a></li>
<li><a class="reference internal" href="#tick-1" id="toc-entry-40">tick()</a></li>
<li><a class="reference internal" href="#write-request" id="toc-entry-41">write_request()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#crypto-plugin" id="toc-entry-42">crypto_plugin</a><ul>
<li><a class="reference internal" href="#decrypt" id="toc-entry-43">decrypt()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#create-smart-ban-plugin" id="toc-entry-44">create_smart_ban_plugin()</a></li>
<li><a class="reference internal" href="#create-ut-pex-plugin" id="toc-entry-45">create_ut_pex_plugin()</a></li>
<li><a class="reference internal" href="#create-ut-metadata-plugin" id="toc-entry-46">create_ut_metadata_plugin()</a></li>
</ul>
</div>
<p>libtorrent has a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface for implementing extensions to the protocol.
These can be general extensions for transferring metadata or peer exchange
extensions, or it could be used to provide a way to customize the protocol
to fit a particular (closed) network.</p>
<p>In short, the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface makes it possible to:</p>
<ul class="simple">
<li>register extension messages (sent in the extension handshake), see
<a class="reference external" href="manual-ref.html#extensions">extensions</a>.</li>
<li>add data and parse data from the extension handshake.</li>
<li>send extension messages and standard bittorrent messages.</li>
<li>override or block the handling of standard bittorrent messages.</li>
<li>save and restore state via the <a class="reference external" href="reference-Session.html#session">session</a> state</li>
<li>see all alerts that are posted</li>
</ul>
<div class="section" id="a-word-of-caution">
<h1>a word of caution</h1>
<p>Writing your own <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is a very easy way to introduce serious bugs such as
dead locks and race conditions. Since a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has access to internal
structures it is also quite easy to sabotage libtorrent's operation.</p>
<p>All the callbacks are always called from the libtorrent network thread. In
case portions of your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> are called from other threads, typically the main
thread, you cannot use any of the member functions on the internal structures
in libtorrent, since those require being called from the libtorrent network
thread . Furthermore, you also need to synchronize your own shared data
within the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>, to make sure it is not accessed at the same time from the
libtorrent thread (through a callback). If you need to send out a message
from another thread, it is advised to use an internal queue, and do the
actual sending in <tt class="docutils literal">tick()</tt>.</p>
<p>Since the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface gives you easy access to internal structures, it
is not supported as a stable API. Plugins should be considered specific to a
specific version of libtorrent. Although, in practice the internals mostly
don't change that dramatically.</p>
</div>
<div class="section" id="plugin-interface">
<h1>plugin-interface</h1>
<p>The <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface consists of three base classes that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> may
implement. These are called <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>, <a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> and <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>.
They are found in the <tt class="docutils literal">&lt;libtorrent/extensions.hpp&gt;</tt> header.</p>
<p>These plugins are instantiated for each <a class="reference external" href="reference-Session.html#session">session</a>, torrent and possibly each peer,
respectively.</p>
<p>For plugins that only need per torrent state, it is enough to only implement
<tt class="docutils literal">torrent_plugin</tt> and pass a constructor function or function object to
<tt class="docutils literal"><span class="pre">session::add_extension()</span></tt> or <tt class="docutils literal"><span class="pre">torrent_handle::add_extension()</span></tt> (if the
torrent has already been started and you want to hook in the extension at
run-time).</p>
<p>The signature of the function is:</p>
<pre class="code c++ literal-block">
<span class="name">std</span><span class="operator">::</span><span class="name">shared_ptr</span><span class="operator">&lt;</span><span class="name">torrent_plugin</span><span class="operator">&gt;</span><span class="whitespace"> </span><span class="punctuation">(</span><span class="operator">*</span><span class="punctuation">)(</span><span class="name">torrent_handle</span><span class="whitespace"> </span><span class="keyword">const</span><span class="operator">&amp;</span><span class="punctuation">,</span><span class="whitespace"> </span><span class="name">client_data_t</span><span class="punctuation">);</span>
</pre>
<p>The second argument is the userdata passed to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> or
<tt class="docutils literal"><span class="pre">torrent_handle::add_extension()</span></tt>.</p>
<p>The function should return a <tt class="docutils literal"><span class="pre">std::shared_ptr&lt;torrent_plugin&gt;</span></tt> which
may or may not be 0. If it is a nullptr, the extension is simply ignored
for this torrent. If it is a valid pointer (to a class inheriting
<tt class="docutils literal">torrent_plugin</tt>), it will be associated with this torrent and callbacks
will be made on torrent events.</p>
<p>For more elaborate plugins which require <a class="reference external" href="reference-Session.html#session">session</a> wide state, you would
implement <tt class="docutils literal">plugin</tt>, construct an object (in a <tt class="docutils literal"><span class="pre">std::shared_ptr</span></tt>) and pass
it in to <tt class="docutils literal"><span class="pre">session::add_extension()</span></tt>.</p>
</div>
<div class="section" id="custom-alerts">
<h1>custom alerts</h1>
<p>Since plugins are running within internal libtorrent threads, one convenient
way to communicate with the client is to post custom alerts.</p>
<p>The expected interface of any <a class="reference external" href="reference-Alerts.html#alert">alert</a>, apart from deriving from the <a class="reference external" href="reference-Alerts.html#alert">alert</a>
base class, looks like this:</p>
<pre class="literal-block">
static const int alert_type = <em>&lt;unique alert ID&gt;</em>;
virtual int type() const { return alert_type; }

virtual std::string message() const;

static const alert_category_t static_category = <em>&lt;bitmask of alert::category_t flags&gt;</em>;
virtual alert_category_t category() const { return static_category; }

virtual char const* what() const { return <em>&lt;string literal of the name of this alert&gt;</em>; }
</pre>
<p>The <tt class="docutils literal">alert_type</tt> is used for the type-checking in <tt class="docutils literal">alert_cast</tt>. It must
not collide with any other <a class="reference external" href="reference-Alerts.html#alert">alert</a>. The built-in alerts in libtorrent will
not use <a class="reference external" href="reference-Alerts.html#alert">alert</a> type IDs greater than <tt class="docutils literal">user_alert_id</tt>. When defining your
own <a class="reference external" href="reference-Alerts.html#alert">alert</a>, make sure it's greater than this constant.</p>
<p><tt class="docutils literal">type()</tt> is the run-time equivalence of the <tt class="docutils literal">alert_type</tt>.</p>
<p>The <tt class="docutils literal">message()</tt> virtual function is expected to construct a useful
string representation of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> and the event or data it represents.
Something convenient to put in a log file for instance.</p>
<p><tt class="docutils literal">clone()</tt> is used internally to copy alerts. The suggested implementation
of simply allocating a new instance as a copy of <tt class="docutils literal">*this</tt> is all that's
expected.</p>
<p>The static category is required for checking whether or not the category
for a specific <a class="reference external" href="reference-Alerts.html#alert">alert</a> is enabled or not, without instantiating the <a class="reference external" href="reference-Alerts.html#alert">alert</a>.
The <tt class="docutils literal">category</tt> virtual function is the run-time equivalence.</p>
<p>The <tt class="docutils literal">what()</tt> virtual function may simply be a string literal of the class
name of your <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<p>For more information, see the <a class="reference external" href="reference-Alerts.html">alert section</a>.</p>
<a name="peer_connection_handle"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+peer_connection_handle%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="peer-connection-handle">
<h1>peer_connection_handle</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/peer_connection_handle.hpp">libtorrent/peer_connection_handle.hpp</a>&quot;</p>
<p>the <a class="reference external" href="reference-Plugins.html#peer_connection_handle">peer_connection_handle</a> class provides a handle to the internal peer
connection object, to be used by plugins. This is a low level interface that
may not be stable across libtorrent versions</p>
<pre class="literal-block">
struct peer_connection_handle
{
   explicit <strong>peer_connection_handle</strong> (std::weak_ptr&lt;peer_connection&gt; impl);
   connection_type <strong>type</strong> () const;
   void <strong>add_extension</strong> (std::shared_ptr&lt;peer_plugin&gt;);
   peer_plugin const* <strong>find_plugin</strong> (string_view type) const;
   bool <strong>is_seed</strong> () const;
   bool <strong>upload_only</strong> () const;
   peer_id const&amp; <strong>pid</strong> () const;
   bool <strong>has_piece</strong> (piece_index_t i) const;
   bool <strong>is_interesting</strong> () const;
   bool <strong>is_choked</strong> () const;
   bool <strong>is_peer_interested</strong> () const;
   bool <strong>has_peer_choked</strong> () const;
   void <strong>choke_this_peer</strong> ();
   void <strong>maybe_unchoke_this_peer</strong> ();
   void <strong>get_peer_info</strong> (peer_info&amp; p) const;
   torrent_handle <strong>associated_torrent</strong> () const;
   <a class="reference external" href="tcp::endpoint">tcp::endpoint</a> const&amp; <strong>remote</strong> () const;
   <a class="reference external" href="tcp::endpoint">tcp::endpoint</a> <strong>local_endpoint</strong> () const;
   bool <strong>is_disconnecting</strong> () const;
   void <strong>disconnect</strong> (error_code const&amp; ec, operation_t op
      , disconnect_severity_t = peer_connection_interface::normal);
   bool <strong>is_connecting</strong> () const;
   bool <strong>is_outgoing</strong> () const;
   bool <strong>on_local_network</strong> () const;
   bool <strong>ignore_unchoke_slots</strong> () const;
   bool <strong>failed</strong> () const;
   bool <strong>should_log</strong> (peer_log_alert::direction_t direction) const;
   void <strong>peer_log</strong> (peer_log_alert::direction_t direction
      , char const* event, char const* fmt = &quot;&quot;, ...) const TORRENT_FORMAT(4,5);
   bool <strong>can_disconnect</strong> (error_code const&amp; ec) const;
   bool <strong>has_metadata</strong> () const;
   bool <strong>in_handshake</strong> () const;
   void <strong>send_buffer</strong> (char const* begin, int size);
   time_point <strong>time_of_last_unchoke</strong> () const;
   std::time_t <strong>last_seen_complete</strong> () const;
   bool <strong>operator&lt;</strong> (peer_connection_handle const&amp; o) const;
   bool <strong>operator!=</strong> (peer_connection_handle const&amp; o) const;
   bool <strong>operator==</strong> (peer_connection_handle const&amp; o) const;
   std::shared_ptr&lt;peer_connection&gt; <strong>native_handle</strong> () const;
};
</pre>
<a name="bt_peer_connection_handle"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+bt_peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+bt_peer_connection_handle%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="bt-peer-connection-handle">
<h1>bt_peer_connection_handle</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/peer_connection_handle.hpp">libtorrent/peer_connection_handle.hpp</a>&quot;</p>
<p>The <a class="reference external" href="reference-Plugins.html#bt_peer_connection_handle">bt_peer_connection_handle</a> provides a handle to the internal bittorrent
peer connection object to plugins. It's low level and may not be a stable API
across libtorrent versions.</p>
<pre class="literal-block">
struct bt_peer_connection_handle : peer_connection_handle
{
   explicit <strong>bt_peer_connection_handle</strong> (peer_connection_handle pc);
   bool <strong>packet_finished</strong> () const;
   bool <strong>support_extensions</strong> () const;
   bool <strong>supports_encryption</strong> () const;
   void <strong>switch_send_crypto</strong> (std::shared_ptr&lt;crypto_plugin&gt; crypto);
   void <strong>switch_recv_crypto</strong> (std::shared_ptr&lt;crypto_plugin&gt; crypto);
   std::shared_ptr&lt;bt_peer_connection&gt; <strong>native_handle</strong> () const;
};
</pre>
<a name="plugin"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+plugin&labels=documentation&body=Documentation+under+heading+%22class+plugin%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="plugin">
<h1>plugin</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>this is the base class for a <a class="reference external" href="reference-Session.html#session">session</a> <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>. One primary feature
is that it is notified of all torrents that are added to the <a class="reference external" href="reference-Session.html#session">session</a>,
and can add its own torrent_plugins.</p>
<pre class="literal-block">
struct plugin
{
   virtual feature_flags_t <strong>implemented_features</strong> ();
   virtual std::shared_ptr&lt;torrent_plugin&gt; <strong>new_torrent</strong> (torrent_handle const&amp;, client_data_t);
   virtual void <strong>added</strong> (session_handle const&amp;);
   virtual void <strong>abort</strong> ();
   virtual bool <strong>on_dht_request</strong> (string_view <em>/* query */</em>
      , udp::endpoint const&amp; <em>/* source */</em>, bdecode_node const&amp; <em>/* message */</em>
      , entry&amp; <em>/* response */</em>);
   virtual void <strong>on_alert</strong> (alert const*);
   virtual bool <strong>on_unknown_torrent</strong> (info_hash_t const&amp; <em>/* info_hash */</em>
      , peer_connection_handle const&amp; <em>/* pc */</em>, add_torrent_params&amp; <em>/* p */</em>);
   virtual void <strong>on_tick</strong> ();
   virtual uint64_t <strong>get_unchoke_priority</strong> (peer_connection_handle const&amp; <em>/* peer */</em>);
   virtual std::map&lt;std::string, std::string&gt; <strong>save_state</strong> () const;
   virtual void <strong>load_state</strong> (std::map&lt;std::string, std::string&gt; const&amp;);

   static constexpr feature_flags_t <strong>optimistic_unchoke_feature</strong>  = 1_bit;
   static constexpr feature_flags_t <strong>tick_feature</strong>  = 2_bit;
   static constexpr feature_flags_t <strong>dht_request_feature</strong>  = 3_bit;
   static constexpr feature_flags_t <strong>alert_feature</strong>  = 4_bit;
   static constexpr feature_flags_t <strong>unknown_torrent_feature</strong>  = 5_bit;
};
</pre>
<a name="implemented_features()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bimplemented_features%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bimplemented_features%28%29%5D%22+could+be+improved">report issue</a>]</span><div class="section" id="implemented-features">
<h2>implemented_features()</h2>
<pre class="literal-block">
virtual feature_flags_t <strong>implemented_features</strong> ();
</pre>
<p>This function is expected to return a bitmask indicating which features
this <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> implements. Some callbacks on this object may not be called
unless the corresponding feature flag is returned here. Note that
callbacks may still be called even if the corresponding feature is not
specified in the return value here. See feature_flags_t for possible
flags to return.</p>
<a name="new_torrent()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bnew_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bnew_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="new-torrent">
<h2>new_torrent()</h2>
<pre class="literal-block">
virtual std::shared_ptr&lt;torrent_plugin&gt; <strong>new_torrent</strong> (torrent_handle const&amp;, client_data_t);
</pre>
<p>this is called by the <a class="reference external" href="reference-Session.html#session">session</a> every time a new torrent is added.
The <tt class="docutils literal">torrent*</tt> points to the internal torrent object created
for the new torrent. The <a class="reference external" href="reference-Add_Torrent.html#client_data_t">client_data_t</a> is the userdata pointer as
passed in via <a class="reference external" href="reference-Add_Torrent.html#add_torrent_params">add_torrent_params</a>.</p>
<p>If the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns a <a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> instance, it will be added
to the new torrent. Otherwise, return an empty shared_ptr to a
<a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> (the default).</p>
<a name="added()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Badded%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Badded%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="added">
<h2>added()</h2>
<pre class="literal-block">
virtual void <strong>added</strong> (session_handle const&amp;);
</pre>
<p>called when <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is added to a <a class="reference external" href="reference-Session.html#session">session</a></p>
<a name="abort()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Babort%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Babort%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="abort">
<h2>abort()</h2>
<pre class="literal-block">
virtual void <strong>abort</strong> ();
</pre>
<p>called when the <a class="reference external" href="reference-Session.html#session">session</a> is aborted
the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> should perform any cleanup necessary to allow the session's
destruction (e.g. cancel outstanding async operations)</p>
<a name="on_dht_request()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_dht_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_dht_request%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-dht-request">
<h2>on_dht_request()</h2>
<pre class="literal-block">
virtual bool <strong>on_dht_request</strong> (string_view <em>/* query */</em>
      , udp::endpoint const&amp; <em>/* source */</em>, bdecode_node const&amp; <em>/* message */</em>
      , entry&amp; <em>/* response */</em>);
</pre>
<p>called when a dht request is received.
If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> expects this to be called, make sure to include the flag
<tt class="docutils literal">dht_request_feature</tt> in the return value from <a class="reference external" href="reference-Plugins.html#implemented_features()">implemented_features()</a>.</p>
<a name="on_alert()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_alert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_alert%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-alert">
<h2>on_alert()</h2>
<pre class="literal-block">
virtual void <strong>on_alert</strong> (alert const*);
</pre>
<p>called when an <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted alerts that are filtered are not posted.
If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> expects this to be called, make sure to include the flag
<tt class="docutils literal">alert_feature</tt> in the return value from <a class="reference external" href="reference-Plugins.html#implemented_features()">implemented_features()</a>.</p>
<a name="on_unknown_torrent()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_unknown_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_unknown_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-unknown-torrent">
<h2>on_unknown_torrent()</h2>
<pre class="literal-block">
virtual bool <strong>on_unknown_torrent</strong> (info_hash_t const&amp; <em>/* info_hash */</em>
      , peer_connection_handle const&amp; <em>/* pc */</em>, add_torrent_params&amp; <em>/* p */</em>);
</pre>
<p>return true if the <a class="reference external" href="reference-Add_Torrent.html#add_torrent_params">add_torrent_params</a> should be added</p>
<a name="on_tick()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_tick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_tick%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-tick">
<h2>on_tick()</h2>
<pre class="literal-block">
virtual void <strong>on_tick</strong> ();
</pre>
<p>called once per second.
If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> expects this to be called, make sure to include the flag
<tt class="docutils literal">tick_feature</tt> in the return value from <a class="reference external" href="reference-Plugins.html#implemented_features()">implemented_features()</a>.</p>
<a name="get_unchoke_priority()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bget_unchoke_priority%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bget_unchoke_priority%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="get-unchoke-priority">
<h2>get_unchoke_priority()</h2>
<pre class="literal-block">
virtual uint64_t <strong>get_unchoke_priority</strong> (peer_connection_handle const&amp; <em>/* peer */</em>);
</pre>
<p>called when choosing peers to optimistically unchoke. The return value
indicates the peer's priority for unchoking. Lower return values
correspond to higher priority. Priorities above 2^63-1 are reserved.
If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has no priority to assign a peer it should return 2^64-1.
If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> expects this to be called, make sure to include the flag
<tt class="docutils literal">optimistic_unchoke_feature</tt> in the return value from <a class="reference external" href="reference-Plugins.html#implemented_features()">implemented_features()</a>.
If multiple plugins implement this function the lowest return value
(i.e. the highest priority) is used.</p>
<a name="load_state()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bload_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bload_state%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="load-state">
<h2>load_state()</h2>
<pre class="literal-block">
virtual void <strong>load_state</strong> (std::map&lt;std::string, std::string&gt; const&amp;);
</pre>
<p>called on startup while loading settings state from the <a class="reference external" href="reference-Session.html#session_params">session_params</a></p>
<a name="optimistic_unchoke_feature"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Boptimistic_unchoke_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Boptimistic_unchoke_feature%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>optimistic_unchoke_feature</dt>
<dd>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to alter the order of the
optimistic unchoke of peers. i.e. have the on_optimistic_unchoke()
callback be called.</dd>
</dl>
<a name="tick_feature"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Btick_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Btick_feature%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>tick_feature</dt>
<dd>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to have <a class="reference external" href="reference-Plugins.html#on_tick()">on_tick()</a> called</dd>
</dl>
<a name="dht_request_feature"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bdht_request_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bdht_request_feature%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>dht_request_feature</dt>
<dd>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to have <a class="reference external" href="reference-Plugins.html#on_dht_request()">on_dht_request()</a>
called</dd>
</dl>
<a name="alert_feature"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Balert_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Balert_feature%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>alert_feature</dt>
<dd>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to have <a class="reference external" href="reference-Plugins.html#on_alert()">on_alert()</a>
called</dd>
</dl>
<a name="unknown_torrent_feature"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bunknown_torrent_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bunknown_torrent_feature%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>unknown_torrent_feature</dt>
<dd>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to have <a class="reference external" href="reference-Plugins.html#on_unknown_torrent()">on_unknown_torrent()</a>
called even if there is no active torrent in the <a class="reference external" href="reference-Session.html#session">session</a></dd>
</dl>
<a name="torrent_plugin"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_plugin&labels=documentation&body=Documentation+under+heading+%22class+torrent_plugin%22+could+be+improved">report issue</a>]</span></div>
</div>
<div class="section" id="torrent-plugin">
<h1>torrent_plugin</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>Torrent plugins are associated with a single torrent and have a number
of functions called at certain events. Many of its functions have the
ability to change or override the default libtorrent behavior.</p>
<pre class="literal-block">
struct torrent_plugin
{
   virtual std::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection_handle const&amp;);
   virtual void <strong>on_piece_failed</strong> (piece_index_t);
   virtual void <strong>on_piece_pass</strong> (piece_index_t);
   virtual void <strong>tick</strong> ();
   virtual bool <strong>on_pause</strong> ();
   virtual bool <strong>on_resume</strong> ();
   virtual void <strong>on_files_checked</strong> ();
   virtual void <strong>on_state</strong> (torrent_status::state_t);
   virtual void <strong>on_add_peer</strong> (tcp::endpoint const&amp;,
      peer_source_flags_t, add_peer_flags_t);

   static constexpr add_peer_flags_t <strong>first_time</strong>  = 1_bit;
   static constexpr add_peer_flags_t <strong>filtered</strong>  = 2_bit;
};
</pre>
<a name="new_connection()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bnew_connection%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bnew_connection%28%29%5D%22+could+be+improved">report issue</a>]</span><div class="section" id="new-connection">
<h2>new_connection()</h2>
<pre class="literal-block">
virtual std::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection_handle const&amp;);
</pre>
<p>This function is called each time a new peer is connected to the torrent. You
may choose to ignore this by just returning a default constructed
<tt class="docutils literal">shared_ptr</tt> (in which case you don't need to override this member
function).</p>
<p>If you need an extension to the peer connection (which most plugins do) you
are supposed to return an instance of your <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <tt class="docutils literal">peer_connection_handle</tt> will be valid as long as the <tt class="docutils literal">shared_ptr</tt>
is being held by the torrent object. So, it is generally a good idea to not
keep a <tt class="docutils literal">shared_ptr</tt> to your own <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>. If you want to keep references
to it, use <tt class="docutils literal">weak_ptr</tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
<a name="on_piece_pass()"></a>
<a name="on_piece_failed()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_piece_pass%28%29+on_piece_failed%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_piece_pass%28%29+on_piece_failed%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-piece-pass-on-piece-failed">
<h2>on_piece_pass() on_piece_failed()</h2>
<pre class="literal-block">
virtual void <strong>on_piece_failed</strong> (piece_index_t);
virtual void <strong>on_piece_pass</strong> (piece_index_t);
</pre>
<p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <tt class="docutils literal">index</tt> is the piece index that was downloaded.
It is possible to access the list of peers that participated in sending the
piece through the <tt class="docutils literal">torrent</tt> and the <tt class="docutils literal">piece_picker</tt>.</p>
<a name="tick()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="tick">
<h2>tick()</h2>
<pre class="literal-block">
virtual void <strong>tick</strong> ();
</pre>
<p>This hook is called approximately once per second. It is a way of making it
easy for plugins to do timed events, for sending messages or whatever.</p>
<a name="on_pause()"></a>
<a name="on_resume()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_pause%28%29+on_resume%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_pause%28%29+on_resume%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-pause-on-resume">
<h2>on_pause() on_resume()</h2>
<pre class="literal-block">
virtual bool <strong>on_pause</strong> ();
virtual bool <strong>on_resume</strong> ();
</pre>
<p>These hooks are called when the torrent is paused and resumed respectively.
The return value indicates if the event was handled. A return value of
<tt class="docutils literal">true</tt> indicates that it was handled, and no other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> after this one
will have this hook function called, and the standard handler will also not be
invoked. So, returning true effectively overrides the standard behavior of
pause or resume.</p>
<p>Note that if you call <tt class="docutils literal">pause()</tt> or <tt class="docutils literal">resume()</tt> on the torrent from your
handler it will recurse back into your handler, so in order to invoke the
standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p>
<a name="on_files_checked()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-files-checked">
<h2>on_files_checked()</h2>
<pre class="literal-block">
virtual void <strong>on_files_checked</strong> ();
</pre>
<p>This function is called when the initial files of the torrent have been
checked. If there are no files to check, this function is called immediately.</p>
<p>i.e. This function is always called when the torrent is in a state where it
can start downloading.</p>
<a name="on_state()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_state%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-state">
<h2>on_state()</h2>
<pre class="literal-block">
virtual void <strong>on_state</strong> (torrent_status::state_t);
</pre>
<p>called when the torrent changes state
the state is one of <a class="reference external" href="reference-Torrent_Status.html#state_t">torrent_status::state_t</a>
enum members</p>
<a name="on_add_peer()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-add-peer">
<h2>on_add_peer()</h2>
<pre class="literal-block">
virtual void <strong>on_add_peer</strong> (tcp::endpoint const&amp;,
      peer_source_flags_t, add_peer_flags_t);
</pre>
<p>called every time a new peer is added to the peer list.
This is before the peer is connected to. For <tt class="docutils literal">flags</tt>, see
torrent_plugin::flags_t. The <tt class="docutils literal">source</tt> argument refers to
the source where we learned about this peer from. It's a
bitmask, because many sources may have told us about the same
peer. For peer source flags, see peer_info::peer_source_flags.</p>
<a name="first_time"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfirst_time%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfirst_time%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>first_time</dt>
<dd>this is the first time we see this peer</dd>
</dl>
<a name="filtered"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfiltered%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfiltered%5D%22+could+be+improved">report issue</a>]</span><dl class="docutils">
<dt>filtered</dt>
<dd>this peer was not added because it was
filtered by the IP filter</dd>
</dl>
<a name="peer_plugin"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_plugin&labels=documentation&body=Documentation+under+heading+%22class+peer_plugin%22+could+be+improved">report issue</a>]</span></div>
</div>
<div class="section" id="peer-plugin">
<h1>peer_plugin</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>peer plugins are associated with a specific peer. A peer could be
both a regular bittorrent peer (<tt class="docutils literal">bt_peer_connection</tt>) or one of the
web seed connections (<tt class="docutils literal">web_peer_connection</tt> or <tt class="docutils literal">http_seed_connection</tt>).
In order to only attach to certain peers, make your
torrent_plugin::new_connection only return a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> for certain peer
connection types</p>
<pre class="literal-block">
struct peer_plugin
{
   virtual string_view <strong>type</strong> () const;
   virtual void <strong>add_handshake</strong> (entry&amp;);
   virtual void <strong>on_disconnect</strong> (error_code const&amp;);
   virtual void <strong>on_connected</strong> ();
   virtual bool <strong>on_handshake</strong> (span&lt;char const&gt;);
   virtual bool <strong>on_extension_handshake</strong> (bdecode_node const&amp;);
   virtual bool <strong>on_dont_have</strong> (piece_index_t);
   virtual bool <strong>on_choke</strong> ();
   virtual bool <strong>on_have</strong> (piece_index_t);
   virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
   virtual bool <strong>on_have_none</strong> ();
   virtual bool <strong>on_request</strong> (peer_request const&amp;);
   virtual bool <strong>on_interested</strong> ();
   virtual bool <strong>on_have_all</strong> ();
   virtual bool <strong>on_allowed_fast</strong> (piece_index_t);
   virtual bool <strong>on_not_interested</strong> ();
   virtual bool <strong>on_unchoke</strong> ();
   virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
      , span&lt;char const&gt; <em>/*buf*/</em>);
   virtual bool <strong>on_reject</strong> (peer_request const&amp;);
   virtual bool <strong>on_suggest</strong> (piece_index_t);
   virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
   virtual void <strong>sent_have_all</strong> ();
   virtual void <strong>sent_cancel</strong> (peer_request const&amp;);
   virtual void <strong>sent_reject_request</strong> (peer_request const&amp;);
   virtual void <strong>sent_suggest</strong> (piece_index_t);
   virtual void <strong>sent_allow_fast</strong> (piece_index_t);
   virtual void <strong>sent_have_none</strong> ();
   virtual void <strong>sent_request</strong> (peer_request const&amp;);
   virtual void <strong>sent_choke</strong> ();
   virtual void <strong>sent_unchoke</strong> ();
   virtual void <strong>sent_piece</strong> (peer_request const&amp;);
   virtual void <strong>sent_have</strong> (piece_index_t);
   virtual void <strong>sent_interested</strong> ();
   virtual void <strong>sent_not_interested</strong> ();
   virtual void <strong>sent_payload</strong> (int <em>/* bytes */</em>);
   virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
   virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      span&lt;char const&gt; <em>/*body*/</em>);
   virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      span&lt;char const&gt; <em>/*body*/</em>);
   virtual void <strong>on_piece_failed</strong> (piece_index_t);
   virtual void <strong>on_piece_pass</strong> (piece_index_t);
   virtual void <strong>tick</strong> ();
   virtual bool <strong>write_request</strong> (peer_request const&amp;);
};
</pre>
<a name="type()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span><div class="section" id="type">
<h2>type()</h2>
<pre class="literal-block">
virtual string_view <strong>type</strong> () const;
</pre>
<p>This function is expected to return the name of
the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>.</p>
<a name="add_handshake()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Badd_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Badd_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="add-handshake">
<h2>add_handshake()</h2>
<pre class="literal-block">
virtual void <strong>add_handshake</strong> (entry&amp;);
</pre>
<p>can add entries to the extension handshake
this is not called for web seeds</p>
<a name="on_disconnect()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-disconnect">
<h2>on_disconnect()</h2>
<pre class="literal-block">
virtual void <strong>on_disconnect</strong> (error_code const&amp;);
</pre>
<p>called when the peer is being disconnected.</p>
<a name="on_connected()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_connected%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_connected%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-connected">
<h2>on_connected()</h2>
<pre class="literal-block">
virtual void <strong>on_connected</strong> ();
</pre>
<p>called when the peer is successfully connected. Note that
incoming connections will have been connected by the time
the peer <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is attached to it, and won't have this hook
called.</p>
<a name="on_handshake()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-handshake">
<h2>on_handshake()</h2>
<pre class="literal-block">
virtual bool <strong>on_handshake</strong> (span&lt;char const&gt;);
</pre>
<p>this is called when the initial bittorrent handshake is received.
Returning false means that the other end doesn't support this extension
and will remove it from the list of plugins. this is not called for web
seeds</p>
<a name="on_extension_handshake()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-extension-handshake">
<h2>on_extension_handshake()</h2>
<pre class="literal-block">
virtual bool <strong>on_extension_handshake</strong> (bdecode_node const&amp;);
</pre>
<p>called when the extension handshake from the other end is received
if this returns false, it means that this extension isn't
supported by this peer. It will result in this <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>
being removed from the peer_connection and destructed.
this is not called for web seeds</p>
<a name="on_have_all()"></a>
<a name="on_interested()"></a>
<a name="on_choke()"></a>
<a name="on_dont_have()"></a>
<a name="on_bitfield()"></a>
<a name="on_have()"></a>
<a name="on_request()"></a>
<a name="on_have_none()"></a>
<a name="on_allowed_fast()"></a>
<a name="on_unchoke()"></a>
<a name="on_not_interested()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_have_all%28%29+on_interested%28%29+on_choke%28%29+on_dont_have%28%29+on_bitfield%28%29+on_have%28%29+on_request%28%29+on_have_none%28%29+on_allowed_fast%28%29+on_unchoke%28%29+on_not_interested%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_have_all%28%29+on_interested%28%29+on_choke%28%29+on_dont_have%28%29+on_bitfield%28%29+on_have%28%29+on_request%28%29+on_have_none%28%29+on_allowed_fast%28%29+on_unchoke%28%29+on_not_interested%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-have-all-on-interested-on-choke-on-dont-have-on-bitfield-on-have-on-request-on-have-none-on-allowed-fast-on-unchoke-on-not-interested">
<h2>on_have_all() on_interested() on_choke() on_dont_have() on_bitfield() on_have() on_request() on_have_none() on_allowed_fast() on_unchoke() on_not_interested()</h2>
<pre class="literal-block">
virtual bool <strong>on_dont_have</strong> (piece_index_t);
virtual bool <strong>on_choke</strong> ();
virtual bool <strong>on_have</strong> (piece_index_t);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_none</strong> ();
virtual bool <strong>on_request</strong> (peer_request const&amp;);
virtual bool <strong>on_interested</strong> ();
virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_allowed_fast</strong> (piece_index_t);
virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_unchoke</strong> ();
</pre>
<p>returning true from any of the message handlers
indicates that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has handled the message.
it will break the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> chain traversing and not let
anyone else handle the message, including the default
handler.</p>
<a name="on_piece()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-piece">
<h2>on_piece()</h2>
<pre class="literal-block">
virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
      , span&lt;char const&gt; <em>/*buf*/</em>);
</pre>
<p>This function is called when the peer connection is receiving
a piece. <tt class="docutils literal">buf</tt> points (non-owning pointer) to the data in an
internal immutable disk buffer. The length of the data is specified
in the <tt class="docutils literal">length</tt> member of the <tt class="docutils literal">piece</tt> parameter.
returns true to indicate that the piece is handled and the
rest of the logic should be ignored.</p>
<a name="sent_unchoke()"></a>
<a name="sent_not_interested()"></a>
<a name="sent_have()"></a>
<a name="sent_interested()"></a>
<a name="sent_piece()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_unchoke%28%29+sent_not_interested%28%29+sent_have%28%29+sent_interested%28%29+sent_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_unchoke%28%29+sent_not_interested%28%29+sent_have%28%29+sent_interested%28%29+sent_piece%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="sent-unchoke-sent-not-interested-sent-have-sent-interested-sent-piece">
<h2>sent_unchoke() sent_not_interested() sent_have() sent_interested() sent_piece()</h2>
<pre class="literal-block">
virtual void <strong>sent_unchoke</strong> ();
virtual void <strong>sent_piece</strong> (peer_request const&amp;);
virtual void <strong>sent_have</strong> (piece_index_t);
virtual void <strong>sent_interested</strong> ();
virtual void <strong>sent_not_interested</strong> ();
</pre>
<p>called after a choke message has been sent to the peer</p>
<a name="sent_payload()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_payload%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_payload%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="sent-payload">
<h2>sent_payload()</h2>
<pre class="literal-block">
virtual void <strong>sent_payload</strong> (int <em>/* bytes */</em>);
</pre>
<p>called after piece data has been sent to the peer
this can be used for stats book keeping</p>
<a name="can_disconnect()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="can-disconnect">
<h2>can_disconnect()</h2>
<pre class="literal-block">
virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
</pre>
<p>called when libtorrent think this peer should be disconnected.
if the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns false, the peer will not be disconnected.</p>
<a name="on_extended()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extended%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extended%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-extended">
<h2>on_extended()</h2>
<pre class="literal-block">
virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      span&lt;char const&gt; <em>/*body*/</em>);
</pre>
<p>called when an extended message is received. If returning true,
the message is not processed by any other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> and if false
is returned the next <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> in the chain will receive it to
be able to handle it. This is not called for web seeds.
thus function may be called more than once per incoming message, but
only the last of the calls will the <tt class="docutils literal">body</tt> size equal the <tt class="docutils literal">length</tt>.
i.e. Every time another fragment of the message is received, this
function will be called, until finally the whole message has been
received. The purpose of this is to allow early disconnects for invalid
messages and for reporting progress of receiving large messages.</p>
<a name="on_unknown_message()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-unknown-message">
<h2>on_unknown_message()</h2>
<pre class="literal-block">
virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      span&lt;char const&gt; <em>/*body*/</em>);
</pre>
<p>this is not called for web seeds</p>
<a name="on_piece_pass()"></a>
<a name="on_piece_failed()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece_pass%28%29+on_piece_failed%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece_pass%28%29+on_piece_failed%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="on-piece-pass-on-piece-failed-1">
<h2>on_piece_pass() on_piece_failed()</h2>
<pre class="literal-block">
virtual void <strong>on_piece_failed</strong> (piece_index_t);
virtual void <strong>on_piece_pass</strong> (piece_index_t);
</pre>
<p>called when a piece that this peer participated in either
fails or passes the hash_check</p>
<a name="tick()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="tick-1">
<h2>tick()</h2>
<pre class="literal-block">
virtual void <strong>tick</strong> ();
</pre>
<p>called approximately once every second</p>
<a name="write_request()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bwrite_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bwrite_request%28%29%5D%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="write-request">
<h2>write_request()</h2>
<pre class="literal-block">
virtual bool <strong>write_request</strong> (peer_request const&amp;);
</pre>
<p>called each time a request message is to be sent. If true
is returned, the original request message won't be sent and
no other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> will have this function called.</p>
<a name="crypto_plugin"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+crypto_plugin&labels=documentation&body=Documentation+under+heading+%22class+crypto_plugin%22+could+be+improved">report issue</a>]</span></div>
</div>
<div class="section" id="crypto-plugin">
<h1>crypto_plugin</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<pre class="literal-block">
struct crypto_plugin
{
   virtual void <strong>set_outgoing_key</strong> (span&lt;char const&gt; key) = 0;
   virtual void <strong>set_incoming_key</strong> (span&lt;char const&gt; key) = 0;
   <strong>encrypt</strong> (span&lt;span&lt;char&gt;&gt; <em>/*send_vec*/</em>) = 0;
   virtual std::tuple&lt;int, int, int&gt; <strong>decrypt</strong> (span&lt;span&lt;char&gt;&gt; <em>/*receive_vec*/</em>) = 0;
};
</pre>
<a name="decrypt()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:crypto_plugin%3A%3A%5Bdecrypt%28%29%5D&labels=documentation&body=Documentation+under+heading+%22crypto_plugin%3A%3A%5Bdecrypt%28%29%5D%22+could+be+improved">report issue</a>]</span><div class="section" id="decrypt">
<h2>decrypt()</h2>
<pre class="literal-block">
virtual std::tuple&lt;int, int, int&gt; <strong>decrypt</strong> (span&lt;span&lt;char&gt;&gt; <em>/*receive_vec*/</em>) = 0;
</pre>
<p>decrypt the provided buffers.
returns is a tuple representing the values
(consume, produce, packet_size)</p>
<p>consume is set to the number of bytes which should be trimmed from the
head of the buffers, default is 0</p>
<p>produce is set to the number of bytes of payload which are now ready to
be sent to the upper layer. default is the number of bytes passed in receive_vec</p>
<p>packet_size is set to the minimum number of bytes which must be read to
advance the next step of decryption. default is 0</p>
<a name="create_smart_ban_plugin()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_smart_ban_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_smart_ban_plugin%28%29%22+could+be+improved">report issue</a>]</span></div>
</div>
<div class="section" id="create-smart-ban-plugin">
<h1>create_smart_ban_plugin()</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions/smart_ban.hpp">libtorrent/extensions/smart_ban.hpp</a>&quot;</p>
<pre class="literal-block">
std::shared_ptr&lt;torrent_plugin&gt; <strong>create_smart_ban_plugin</strong> (torrent_handle const&amp;, client_data_t);
</pre>
<p>constructor function for the smart ban extension. The extension keeps
track of the data peers have sent us for failing pieces and once the
piece completes and passes the hash check bans the peers that turned
out to have sent corrupt data.
This function can either be passed in the add_torrent_params::extensions
field, or via <a class="reference external" href="reference-Torrent_Handle.html#add_extension()">torrent_handle::add_extension()</a>.</p>
<a name="create_ut_pex_plugin()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_pex_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_pex_plugin%28%29%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="create-ut-pex-plugin">
<h1>create_ut_pex_plugin()</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions/ut_pex.hpp">libtorrent/extensions/ut_pex.hpp</a>&quot;</p>
<pre class="literal-block">
std::shared_ptr&lt;torrent_plugin&gt; <strong>create_ut_pex_plugin</strong> (torrent_handle const&amp;, client_data_t);
</pre>
<p>constructor function for the ut_pex extension. The ut_pex
extension allows peers to gossip about their connections, allowing
the swarm stay well connected and peers aware of more peers in the
swarm. This extension is enabled by default unless explicitly disabled in
the <a class="reference external" href="reference-Session.html#session">session</a> constructor.</p>
<p>This can either be passed in the add_torrent_params::extensions field, or
via <a class="reference external" href="reference-Torrent_Handle.html#add_extension()">torrent_handle::add_extension()</a>.</p>
<a name="create_ut_metadata_plugin()"></a><span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_metadata_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_metadata_plugin%28%29%22+could+be+improved">report issue</a>]</span></div>
<div class="section" id="create-ut-metadata-plugin">
<h1>create_ut_metadata_plugin()</h1>
<p>Declared in &quot;<a class="reference external" href="include/libtorrent/extensions/ut_metadata.hpp">libtorrent/extensions/ut_metadata.hpp</a>&quot;</p>
<pre class="literal-block">
std::shared_ptr&lt;torrent_plugin&gt; <strong>create_ut_metadata_plugin</strong> (torrent_handle const&amp;, client_data_t);
</pre>
<p>constructor function for the ut_metadata extension. The ut_metadata
extension allows peers to request the .torrent file (or more
specifically the info-dictionary of the .torrent file) from each
other. This is the main building block in making magnet links work.
This extension is enabled by default unless explicitly disabled in
the <a class="reference external" href="reference-Session.html#session">session</a> constructor.</p>
<p>This can either be passed in the add_torrent_params::extensions field, or
via <a class="reference external" href="reference-Torrent_Handle.html#add_extension()">torrent_handle::add_extension()</a>.</p>
</div>

    </div>
    </div>
    <div id="gradient"></div>
    <div id="filler">
    <div id="footer">
    <div><a href="index.html">home</a></div>
    <div><a href="https://blog.libtorrent.org">blog</a></div>
    <div><a href="utp.html">uTP</a></div>
    <div><a href="https://sourceforge.net/projects/libtorrent/files/libtorrent/">download</a></div>
    <div><a href="reference.html">documentation</a></div>
    <div><a href="dht_store.html">DHT put extension</a></div>
    <div><a href="python_binding.html">python bindings</a></div>
    <div><a href="features-ref.html">features</a></div>
    <div><a href="dht_sec.html">DHT security extension</a></div>
    <div><a href="https://sourceforge.net/p/libtorrent/mailman/libtorrent-discuss/">mailing list archive</a></div>
    <div><a href="contributing.html">contributing</a></div>
    <div><a href="streaming.html">streaming</a></div>
    <div><a href="https://github.com/arvidn/libtorrent/issues">report a bug</a></div>
    <div><a href="building.html">building</a></div>
    <div><a href="bittorrent.pdf">bittorrent slides</a></div>
    </div>
	</div>

</div>
</body>
</html>
